﻿//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IPopulateHelper.cs
//
//  Description: Interface for manually populating persistent objects.
// 
//--------------------------------------------------------------------------

using System;

namespace Chili.Opf3
{
	/// <summary>
	/// This interface that is implemented by objects that are populated manually.
	/// </summary>
	/// <remarks>
	/// 	<para>This interface is implemented by classes that won't let the framework
	///     automatically populate them with data or retrieve data from them via reflection.</para>
	/// 	<para>If the framework encounters a persistent object that implements this
	///     interface it gives the content of the field from the storage (in combination with
	///     the name of the property that is mapped to that field) as value to the class. The
	///     class itself has to populate the property in an appropriate way.</para>
	/// 	<para><b>Attention:</b> Throw an exception if something goes wrong while manually
	///     populating the object. This will solve problems like loss of data etc.</para>
	/// </remarks>
	/// <example>
	///     The following example shows how to implement the interface. 
	///     <code lang="CS">
	/// [Persistent("USER")]
	/// public class User : IPopulateHelper
	/// {
	///     public object this[string propertyName]
	///     {
	///         get
	///         {
	///             switch(propertyName)
	///             {
	///                 case "Name":
	///                     return Name;
	///                 // ... Other properties.
	///                 default:
	///                     throw new Exception();
	///             }
	///         }
	///         set
	///         {
	///             switch(propertyName)
	///             {
	///                 case "Name":
	///                     Name = value;
	///                     break;
	///                 // ... Other properties.
	///                 default:
	///                     throw new Exception();
	///             }
	///         }
	///     }
	///  
	///     // ... Other properties and code.
	/// }
	///     </code>
	/// </example>
	public interface IPopulateHelper
	{
		/// <summary>
		/// Indexer used to populate the persistent object. For additional information of how
		/// to implement the interface look at the
		/// <see cref="Opf3.IPopulateHelper">IPopulateHelper</see> class definition.
		/// </summary>
		/// <value>Returns the value of the requested property.</value>
		/// <param name="propertyName">
		/// Name of the property that's data is retrieved or that is populated with data from
		/// the storage.
		/// </param>
		object this[string propertyName]
		{
			get;
			set;
		}
	}
}